<HTML><HEAD><TITLE>setval(++ElemSpec, ?Value)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Non-logical Variables, Arrays, Bags, Shelves and Stores</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>setval(++ElemSpec, ?Value)</H1>
Sets the value of a non-logical variable, array element, or reference to the value Value.
<DL>
<DT><EM>ElemSpec</EM></DT>
<DD>Atom (non-logical variable or reference) or fully instantiated compound term with positive integer arguments (array element specification).
</DD>
<DT><EM>Value</EM></DT>
<DD>Prolog term.
</DD>
</DL>
<H2>Description</H2>
   If ElemSpec is the name of a visible non-logical variable, its
   value gets set to a copy of the term value.  If there was no
   variable visible from the caller module, a local non-logical
   variable is created and its value is set.  The value of a
   non-logical variable can be overwritten any number of times with
   any data type, including a free variable. Values of non-logical
   variables are copies of the original term and persist across failures.
<P>
   If ElemSpec is a compound term, it must specify a visible array element:
   all its argument must be non negative integers smaller than the bounds
   specified with array/1 or array/2.
   If the array has been created with array/2, then Value is restricted
   to the type given in the declaration; otherwise Value can have any type,
   including a free variable.  Its value can be overwritten any number of times.
   Values of non-logical arrays are copies of the original term and persist
   across failures.
<P>
   If ElemSpec is the name of a visible reference, its value will be set
   to the term value.  Unlike for non-logical variables, the value of a
   reference is the original term, not a copy. Setting the value of a
   reference is undone on backtracking, i.e. the value of the reference
   reverts to what it was before being changed.

<H3>Modes and Determinism</H3><UL>
<LI>setval(++, ?) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>ElemSpec is not ground
<DT><EM>(4) instantiation fault </EM>
<DD>ElemSpec is of an array of type integer, float or byte and Value is not instantiated
<DT><EM>(5) type error </EM>
<DD>the type of Value is not of the declared type of ElemSpec.
<DT><EM>(5) type error </EM>
<DD>ElemSpec is a structure whose arguments are not all integers.
<DT><EM>(5) type error </EM>
<DD>ElemSpec is neither an atom nor a ground structure.
<DT><EM>(6) out of range </EM>
<DD>Array index in ElemSpec is out of bounds.
<DT><EM>(41) array or global variable does not exist </EM>
<DD>ElemSpec is an element of an array which does not exist.
</DL>
<H2>Examples</H2>
<PRE>
Success:
      local(array(a(4,3))),
          setval(a(0,0), 2),
          setval(a(1,2), "string"),
          % overwrite a(0,0) (= 2) with a free variable
          setval(a(0,0), X).
      local(array(a(4), float)),
          setval(a(0), 2.0),
          setval(a(3), -19.6).
      setval(i, 4).
      setval(j, 4),
           setval(j, "string data").

Error:
      setval(A, 2.0).            (Error 4).
      setval(a(V), 2.0).         (Error 4).
      setval(a(1.0), 2).         (Error 5).
      setval("b(0)", 2.0).       (Error 5).
      local(array(a(4))),
          setval(a(-2), 2).      (Error 6).
      local(array(a(9), integer)),
          setval(a(9), 4).       (Error 6).
      setval(no_array(1), 2.0).  (Error 41).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/storage/decval-1.html">decval / 1</A>, <A HREF="../../kernel/storage/erase_array-1.html">erase_array / 1</A>, <A HREF="../../kernel/storage/incval-1.html">incval / 1</A>, <A HREF="../../kernel/storage/array-1.html">array / 1</A>, <A HREF="../../kernel/storage/array-2.html">array / 2</A>, <A HREF="../../kernel/storage/variable-1.html">variable / 1</A>, <A HREF="../../kernel/storage/getval-2.html">getval / 2</A>
</BODY></HTML>
